import { Link } from '@brillout/docpress'

import { UiFrameworkExtension, ProvidedBy, ConfigSpec } from '../../components'

<ConfigSpec
  default={<>
    <code>false</code> (or <code>true</code> if using a <Link href="/extensions">Vike extension</Link> that requires streaming)
  </>}
  providedBy={<ProvidedBy>the <code>stream</code> setting</ProvidedBy>}
  requires={<Link href="/ssr"><code>ssr: true</code></Link>}
  isTypeOneLiner
>
`boolean | 'web' | 'node' {:ts}`
</ConfigSpec>

The `stream` setting allows you to:
- Enable or disable HTML Streaming.
- Specify the stream type (either a [Node.js Stream](https://nodejs.org/api/stream.html) or a [Web Stream](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API)).

<span id="what-is-streaming"></span>

> **What is HTML Streaming?** If you're unfamiliar with HTML streaming then check out [this explanation of SSR, HTML streaming, and Progressive Rendering](https://github.com/reactwg/react-18/discussions/37). Although it explains it in the context of React, we also recommend reading it if you use a UI framework other than React.

```ts
// /pages/+config.ts

import type { Config } from 'vike/types'

export default {
  // Enable HTML Streaming. Let Vike extensions decide whether to use a Node.js or Web stream.
  stream: true,
  // Enable HTML Streaming. Force the stream to be a Web Stream.
  stream: 'web',
  // Enable HTML Streaming. Force the stream to be a Node.js Stream.
  stream: 'node'
} satisfies Config
```

> **Why doesn't it seem to work?** If you enable HTML Streaming but the HTML is still sent all at once, note that:
> - **The <Link href="/data">`+data` hook</Link> doesn't trigger HTML Streaming** — the `+data` hook applies to the whole page and is fully awaited before rendering starts. [A slow `+data` hook](https://github.com/vikejs/vike-react/pull/189/commits/a834d9ba0f259f0f2d332e46a99cc9d895cbedf2) still results in the HTML being sent all at once. To see HTML streaming in action, use a Vike extension like [`vike-react-query`](https://github.com/vikejs/vike-react/tree/main/packages/vike-react-query#readme)/[`vike-vue-query`](https://github.com/vikejs/vike-vue/tree/main/packages/vike-vue-query#readme)/[`vike-solid-query`](https://github.com/vikejs/vike-solid/tree/main/packages/vike-solid-query#readme) (and upcoming Telefunc integrations such as [`vike-react-telefunc`](https://github.com/vikejs/vike-react/issues/131)).
> - **By default, HTML streaming is disabled for bots**. For example, the [`User-Agent` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/User-Agent) sent by [`curl`](https://curl.se) is interpreted as a bot. See [`react-streaming` > Bots](https://github.com/brillout/react-streaming#bots).

## Inheritance

Enable for all your pages:

```ts
// /pages/+config.ts

import type { Config } from 'vike/types'

// This config applies to all pages (/pages/**).
export default {
  stream: false
} satisfies Config
```

Enable only for some pages:

```ts
// /pages/admin/+config.ts

import type { Config } from 'vike/types'

/* This config applies only to admin pages (/pages/admin/**) such as:
   FILESYSTEM                            URL
   /pages/admin/+Page.ts                 /admin
   /pages/admin/user/@id/+Page.ts        /admin/user/@id
   /pages/admin/product/@id/+Page.ts     /admin/product/@id
*/
export default {
  stream: false
} satisfies Config
```

> For better config organization, you can use <Link href="/routing#groups">page groups</Link>.


## Without `vike-{react,vue,solid}`

In case you don't use a <UiFrameworkExtension />, you can:
 - Integrate HTML streaming yourself, see <Link href="/streaming" />.
 - Implement the `stream` setting yourself by using <Link href="/meta">meta</Link>. Examples:
   - [`vike-react` source code](https://github.com/vikejs/vike-react/blob/main/packages/vike-react)
   - [`vike-vue` source code](https://github.com/vikejs/vike-vue/blob/main/packages/vike-vue)
   - [`vike-solid` source code](https://github.com/vikejs/vike-solid/blob/main/vike-solid)


## See also

- <Link href="/streaming" />
- <Link href="/ssr" />
- [Explanation of SSR, HTML streaming, and Progressive Rendering](https://github.com/reactwg/react-18/discussions/37)
- [Node.js Streams](https://nodejs.org/api/stream.html) (Node.js documentation)
- [Web Streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API) (MDN documentation)
